package etesp.bd3a;

import java.util.Date;

/**
 * A interface BD3A é o ponto principal de utilizacao da API BD3A. Ela
 * fornece os métodos necessários para manipulação de registros em bancos
 * de dados RMS.<br><br>
 * 
 * Exemplo de utilizacao:<br>
 * Suponha uma definicao de tabela como a se segue:<br>
 * <ol>
 * 	<li><b>nome</b> - java.lang.String
 * 	<li><b>data nascimento</b> - java.util.Date
 * 	<li><b>qtd</b> - int
 * </ol>
 * 
 * <pre>
 * BD3A banco = new BD3ARMSImpl("DB_NAME");
 * banco.abrir();
 * 
 * // gravacao de registro
 * banco.setString(1, "nome");
 * banco.setDate(2, new Date());
 * banco.setInt(3, 10);
 * int id = banco.salvar(); // insere um novo registro no banco
 * 
 * // alteracao
 * int id = 143;
 * banco.setId(id);
 * banco.setString(1, "novo nome");
 * banco.setDate(2, new Date());
 * banco.setInt(3, 20);
 * banco.salvar(); // verifica que o ID foi configurado e altera o registro corespondente
 * 
 * // remocao
 * int id = 48;
 * banco.remover(id); // remove o ID informado
 * 
 * // recuperando dados
 * int = 92;
 * Registro dado = banco.listar(id);
 * </pre>
 * 
 * @see Registro
 */
public interface BD3A {

	/**
	 * Disponibiliza o Banco de dados para as operacoes
	 * @return Uma referência ao {@link BD3A} corrente
	 */
	public BD3A abrir();
	
	/**
	 * Configura o <code>valor</code> como uma String a ser inserida
	 * na <code>coluna</code> informada.
	 * 
	 * @param coluna O indice da coluna a ser utilizada
	 * @param valor O valor a ser guardado
	 */
	public void setString(int coluna, String valor);

	/**
	 * Configura o <code>valor</code> como um inteiro a ser inserido
	 * na <code>coluna</code> informada.
	 * 
	 * @param coluna O indice da coluna a ser utilizada
	 * @param valor O valor a ser guardado
	 */
	public void setInt(int coluna, int valor);

	/**
	 * Configura o <code>valor</code> como um inteiro longo a ser inserido
	 * na <code>coluna</code> informada.
	 * 
	 * @param coluna O indice da coluna a ser utilizada
	 * @param valor O valor a ser guardado
	 */
	public void setLong(int coluna, long valor);

	/**
	 * Configura o <code>valor</code> como um double a ser inserido
	 * na <code>coluna</code> informada.
	 * 
	 * @param coluna O indice da coluna a ser utilizada
	 * @param valor O valor a ser guardado
	 */
	public void setDouble(int coluna, double valor);
	
	/**
	 * Configura o <code>valor</code> como uma Data a ser inserida
	 * na <code>coluna</code> informada.
	 * 
	 * @param coluna O indice da coluna a ser utilizada
	 * @param valor O valor a ser guardado
	 */
	public void setDate(int coluna, Date valor);
	
	/**
	 * Executa o procedimento de gravacao do registro de acordo com
	 * as informacoes passadas pelos metodos setter
	 * 
	 * @return o ID do registro recem incluido
	 */
	public int salvar();
	
}
